home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / gui / BGUI11B.lha / docs / methods.doc < prev    next >
Text File  |  1994-09-02  |  8KB  |  192 lines
  1.  
  2.            $RCSfile: methods.doc,v $
  3.         Description: Extra methods documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.3 $
  10.               $Date: 1994/09/02 21:45:27 $
  11. ------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. methods/--background--
  16. groupclass/GRM_DIMENSIONS
  17. windowclass/WM_KEYACTIVE
  18. windowclass/WM_KEYINPUT
  19. windowclass/WM_KEYINACTIVE
  20.  
  21. methods/--background--
  22.  
  23.     DESCRIPTION
  24.         Gadget  classes  that  want to work in a BGUI environment will need to
  25.         know about a set of extra methods on top of the  normal system  gadget
  26.         class methods. This document describes these methods.
  27.  
  28.         Not    all    system    gadgetclass    methods    will    reach   your
  29.         class.  The following   standard   system   gadgetclass   methods  are
  30.         passed onto your class:
  31.  
  32.                 GM_HITTEST
  33.                 GM_RENDER
  34.                 GM_GOACTIVE
  35.                 GM_HANDLEINPUT
  36.                 GM_GOINACTIVE
  37.  
  38.         The  following  methods  are  not used in a BGUI context and therefore
  39.         will not be send to your class:
  40.  
  41.                 GM_HELPTEST
  42.                 GM_LAYOUT
  43.  
  44. groupclass/GRM_DIMENSIONS                            groupclass/GRM_DIMENSIONS
  45.  
  46.     NAME
  47.         GRM_DIMENSIONS
  48.  
  49.     FUNCTION
  50.         To inquire about a gadget object it's minimum  width and  height.  The
  51.         group class sends out this method  to all  it's  members to  ensure  a
  52.         correct  layout.   This  method  uses  the  following  custom  message
  53.         structure:
  54.  
  55.         struct grmDimensions {
  56.                 ULONG                   MethodID;       /* GRM_DIMENSIONS */
  57.                 struct GadgetInfo      *grmd_GInfo;
  58.                 struct RastPort        *grmd_RPort;
  59.                 struct {
  60.                         UWORD          *Width;
  61.                         UWORD          *Height;
  62.                 }                       grmd_MinSize;
  63.                 ULONG                   grmd_Flags;
  64.         };
  65.  
  66.         grmd_GInfo -- This  field  will  always  read  NULL!  It will probably
  67.                 become obsolete in one of the next versions.   Please  do  not
  68.                 make any assumptions about it's contents.   Simply  ignore  it
  69.                 until further notice.
  70.  
  71.         grmd_RPort -- This points to a RastPort which can be  used  to perform
  72.                 text width/height computations etc. in.   Do  *not*  render in
  73.                 this RastPort.
  74.  
  75.         grmd_MinSize --  This  field  contains  two pointers in which you must
  76.                 store the results of your computations.   Note  that you  must
  77.                 *add* your results to the results you got from the superclass.
  78.  
  79.                 Example:
  80.  
  81.                 switch ( msg->MethodID ) {
  82.                     case    GRM_DIMENSIONS:
  83.                         /*
  84.                         **      First the superclass...
  85.                         **/
  86.                         DoSuperMethodA( class, object, msg );
  87.                         /*
  88.                         **      Compute your minimum sizes.
  89.                         **/
  90.                         ...
  91.                         /*
  92.                         **      Add results.
  93.                         **/
  94.                         *( msg->grmd_MinSize.Width  ) += your_min_width;
  95.                         *( msg->grmd_MinSize.Height ) += your_min_height;
  96.                         break;
  97.                 }
  98.  
  99.                 There  might  be  cases  in  which  you  want  to  overide the
  100.                 superclass  results  which  is  perfectly  legal to do but you
  101.                 should be aware that wrong values here might  seriously  screw
  102.                 up the look of the resulting GUI.
  103.  
  104.         grmd_Flags -- This field may contain any of the following flags:
  105.  
  106.                 GDIMF_NO_FRAME -- This will tell the baseclass not to take the
  107.                         attached frame into consideration  when  computing the
  108.                         minimum size.
  109.  
  110. windowclass/WM_KEYACTIVE                              windowclass/WM_KEYACTIVE
  111.  
  112.     NAME
  113.         WM_KEYACTIVE
  114.  
  115.     FUNCTION
  116.         To  tell  the  object  that  it  is  activated  by  a key-press. Uppon
  117.         receiving  this message you can setup any additional resources you may
  118.         need  to  go  active.  This  method  uses the following custom message
  119.         structure:
  120.  
  121.         struct wmKeyInput {
  122.                 ULONG                    MethodID; /* WM_KEY_ACTIVE */
  123.                 struct GadgetInfo       *wmki_GInfo;
  124.                 struct InputEvent       *wmki_IEvent;
  125.                 ULONG                   *wmki_ID;
  126.                 STRPTR                   wmki_Key;
  127.         };
  128.  
  129.         wmki_GInfo -- This points to a GadgetInfo structure.
  130.  
  131.         wmki_IEvent -- A pointer to a InputEvent structure  which is the event
  132.                 that  triggered  the  activation.   The  event class is always
  133.                 IECLASS_RAWKEY. This event can be used to check for  qualifier
  134.                 keys etc.
  135.  
  136.         wmki_ID -- In  this field you can store the ID of the  object when the
  137.                 activation has resulted in a change that needs to be notified.
  138.                 The value put  in  here is  returned  by the  windowclass it's
  139.                 WM_HANDLEIDCMP method.
  140.  
  141.         wmki_Key -- This points to the key string which  has been  assigned to
  142.                 the object with the windowclass it's WM_GADGETKEY method.
  143.  
  144.         This method should return any of the following return codes:
  145.  
  146.         WMKF_MEACTIVE -- The object can go/remains active.
  147.         WMKF_CANCEL -- The keyboard activation is cancelled.
  148.         WMKF_VERIFY -- The keyboard activation is complete and the  ID  set in
  149.                 the wmki_ID field is notified.
  150.         WMKF_ACTIVATE -- Returning this tell's the windowclass to activate the
  151.                 gadget using the intuition.library it's ActivateGadget() call.
  152.  
  153.     SEE ALSO
  154.         windowclass/WM_KEYINPUT, windowclass/WM_KEYINACTIVE,
  155.         windowclass/WM_KEYINACTIVE windowclass/WM_HANDLEIDCMP,
  156.         windowclass/WM_GADGETKEY, intuition.library/ActivateGadget()
  157.  
  158. windowclass/WM_KEYINPUT                                windowclass/WM_KEYINPUT
  159.  
  160.     NAME
  161.         WM_KEYINPUT
  162.  
  163.     FUNCTION
  164.         This method is send to the object  continually  when the  WM_KEYACTIVE
  165.         returned WMKF_MEACTIVE  and the  object has  gone active.  This method
  166.         uses the same custom message structure as the WM_KEYACTIVE method does
  167.         and it should return any of the same return codes as described  in the
  168.         WM_KEYACTIVE method with the exception of WMKF_ACTIVATE.
  169.  
  170.         A good example of this method  is  the  buttonclass  which  uses  this
  171.         method  to  scan  for  the SHIFT  qualifier and/or the ESC  key  which
  172.         both cancel a keyboard button selection.
  173.  
  174.     SEE ALSO
  175.         windowclass/WM_KEYACTIVE
  176.  
  177. windowclass/WM_KEYINACTIVE                          windowclass/WM_KEYINACTIVE
  178.  
  179.     NAME
  180.         WM_KEYINACTIVE
  181.  
  182.     FUNCTION
  183.         When the key-activation of an object is done or aborted by some  other
  184.         event this method is called to tell to object  to go  inactive.   This
  185.         gives you the oppertunity to release the resources that you might have
  186.         obtained with the WM_KEYACTIVE method.
  187.  
  188.         No return code defined.
  189.  
  190.     SEE ALSO
  191.         windowclass/WM_KEYACTIVE
  192.